MacFormat 1996 January/macformat-033.iso/mac/Shareware City/Control Strip/ES 1.0 Package/Programming Stuff/ExtensionsStrip.p

Text File | 1995-10-17 | 16.0 KB | 400 lines | [TEXT/MPS ]

{
     File:        ExtensionsStrip.p

     Contains:    Extensions Strip Specific Interfaces plus the commented out
                 Universal ControlStrip.p Interfaces.

     Version:    Technology:    System 7.1+ (System 7.5+ preferred)
                 Package:    Extensions Strip 1.0

     Copyright:    © 1995 by Ammon Skidmore, Skidperfect Software Inc.
                 All rights reserved.

     Bugs?:        If you find a problem, or have a criticism (they are welcome)
                 with this file, please inform the author at the following address:
                     Internet:    [e-mail]
}

{$IFC UNDEFINED UsingIncludes}
{$SETC UsingIncludes := 0}
{$ENDC}

{$IFC NOT UsingIncludes}
 UNIT ExtensionsStrip;
 INTERFACE
{$ENDC}

{$IFC UNDEFINED __EXTENSIONSSTRIP__}
{$SETC __EXTENSIONSSTRIP__ := 1}

{$I+}
{$SETC ExtensionsStripIncludes := UsingIncludes}
{$SETC UsingIncludes := 1}


{$IFC UNDEFINED __CONTROLSTRIP__}
{$I ControlStrip.p}
{$ENDC}

{$IFC UNDEFINED __APPLEEVENTS__}
{$I AppleEvents.p}
{$ENDC}


{$PUSH}
{$ALIGN MAC68K}
{$LibExport+}

CONST
{    sdevInitModule                = 0;}    { initialize the module}
{    sdevCloseModule                = 1;}    { clean up before being closed}
{    sdevFeatures                = 2;}    { return feature bits}
{    sdevGetDisplayWidth            = 3;}    { returns the width of the module's display}
{    sdevPeriodicTickle            = 4;}    { periodic tickle when nothing else is happening}
{    sdevDrawStatus                = 5;}    { update the interface in the Control Strip}
{    sdevMouseClick                = 6;}    { user clicked on the module's display area in the Control Strip}
{    sdevSaveSettings            = 7;}    { saved any changed settings in module's preferences file}
{    sdevShowBalloonHelp            = 8;}    { puts up a help balloon, if the module has one to display}
    sdevInAppContext            = 2000;    {   called only once after the module specifically        }
                                        {   requested to be executed from inside Extension        }
                                        {   Strip's context. NB: you can return the special        }
                                        {   result values.                                        }
                                        {}
    sdevInterceptedEvent        = 2001;    {    if the module returned the sdevInterceptAllEvents    }
                                        {   flag in its features, then this selector            }
                                        {   will get called before _each_ event is processed    }
                                        {   by Extensions Strip.  Meant to be used with            }
                                        {   _SBGetCurrentEvent so each event can be looked at,    }
                                        {   and modified if necessary (to prevent passing.)        }
                                        {   NB: you can return the special result values.        }
                                        {}
    sdevDragAccept                = 2002;    {    return 0 if you accept the current drag, and        }
                                        {   1 if you do not.  Modules that do not have any        }
                                        {   drag handlers will never get this called.            }
                                        {   NB: sdevDragAccept is only called from within        }
                                        {   Extensions Strip's dragTrackingInWindow.  So it        }
                                        {   is recommended to only check if you accept the drag    }
                                        {   from within your dragTrackingEnterWindow, and then    }
                                        {   set a global var that you can pass onto ES.            }
                                        {}
    sdevEventMask                = 2003;    {    if the module returned the sdevInterceptAllEvents    }
                                        {   flag in its features, this selector will get        }
                                        {   called to find the event mask to use.  Return your    }
                                        {   mask as the result value of the sdev call.            }
                                        {   sdevEventMask is called once upon initialization,    }
                                        {   and every time sdevFeaturesChange is requested.        }


{********************************************************************************************

    Features supported by the module.  If a bit is set, it means that feature is supported.
    All undefined bits are reserved for future use by Apple, and should be set to zero.

********************************************************************************************}
{}
{    Tip: if you clear sdevWantMouseClicks and set sdevDontAutoTrack, your module    }
{    will receive clicks and Extensions Strip (plus Desktop Strip) will not            }
{    auto-hilite your module.                                                        }
{}

{    sdevWantMouseClicks            = 0;}    { notify the module of mouseDown events}
{    sdevDontAutoTrack            = 1;}    { call the module to do mouse tracking}
{    sdevHasCustomHelp            = 2;}    { module provides its own help messages}
{    sdevKeepModuleLocked        = 3;}    { module needs to be locked in the heap}
    sdevHasDragHandlers            = 31;    {    module has installed a drag tracking and/or            }
                                        {   receive handler in the Strip window.                }
                                        {}
    sdevDontPeriodicTickle        = 30;    {    module does not require any idle time so            }
                                        {   by setting this bit it will never get                }
                                        {   called with the sdevPeriodicTickle                     }
                                        {   selector.  Note that you can set this along            }
                                        {   with the sdevInterceptAllEvents bit (if you want)    }
                                        {   and sdevInterceptedEvent will still get called.        }
                                        {   So be nice and set this to help speed up idle        }
                                        {   time processing.                                    }
                                        {}
    sdevInterceptAllEvents        = 29;    {    module wants to be executed before each                }
                                        {   event passes through Extension Strip's                }
                                        {   jGNE filter.  Because the module is allowed            }
                                        {   to modify every event, there is no more need        }
                                        {   for modules, such as Terminator Strip, to            }
                                        {   install their own jGNE filters!                        }
                                        {   NB: You need to return an event mask when your        }
                                        {   module is called by the sdevEventMask selector.        }


{********************************************************************************************

    Special result values returned by the sdevPeriodicTickle and sdevIconMouseClick selectors.
    If a bit is set, the module can request that a specific function is performed by
    the Control Strip.  A result of zero will do nothing.  All undefined bits are reserved
    for future use by Apple, and should be set to zero.

********************************************************************************************}
{}
{    Note: these values can also be returned by the sdevInAppContext and    }
{    sdevInterceptedEvent selectors.                                        }
{}

{    sdevResizeDisplay            = 0;}    { resize the module's display}
{    sdevNeedToSave                = 1;}    { need to save changed settings, when convenient}
{    sdevHelpStateChange            = 2;}    { need to update the help message because of a state change}
{    sdevCloseNow                = 3;}    { close a module because it doesn't want to stay around}
    sdevQueueModule                = 31;    {    module needs to be executed from within                }
                                        {   Extension Strip's context: useful for                }
                                        {   things like sending AppleEvents or                    }
                                        {   creating and tracking new drags.                    }
                                        {}
    sdevFeaturesChange            = 30;    {    module wants to change its feature flags. Useful    }
                                        {   for changing clickable state of the module and        }
                                        {   for locking/unlocking the sdev code.                }

{********************************************************************************************

    miscellaneous

********************************************************************************************}
{    sdevFileType                = 'sdev';}    { module file and code resource type  }
    sdevFileType                = 'Sdev';    { resource type for module's PPC code }

{}

{    sdevMenuItemMark            = '•';}

{    direction values for SBDrawBarGraph}
{    BarGraphSlopeLeft            = -1;}                            { max end of sloping bar graph is on the left}
{    BarGraphFlatRight            = 0; }                            { max end of flat bar graph is on the right}
{    BarGraphSlopeRight            = 1; }                            { max end of sloping bar graph is on the right}

{}
    {}
    gestaltExtensionsStripAttr        = 'CsEs';    {returns Extensions Strip's attributes}

    { currently returned bits from gestaltExtensionsStripAttr: }
    gestaltExtensionsStripExists    = 0;    {Extensions Strip is currently launched}

    {}
    gestaltDesktopStripAttr            = 'CsWT';    { returns the Mice and Men's Desktop Strip    }
                                                { attributes which are supported by            }
                                                { Extensions Strip.  See Desktop Strip's    }
                                                { documentation for details about the bits    }
{}

TYPE
    ModuleReference = LONGINT;

{}

    SBQueueProcPtr = ProcPtr;  { PROCEDURE SBQueue(refCon: LONGINT); }
    SBQueueUPP = UniversalProcPtr;

CONST
    uppQueueProcProcInfo =  $000000C0; { PROCEDURE (4 byte param); }

FUNCTION NewSBQueueProcProc(userRoutine: SBQueueProcPtr): SBQueueUPP;
    {$IFC NOT GENERATINGCFM }
    INLINE $2E9F;
    {$ENDC}

{}

{********************************************************************************************

    utility routines to provide standard interface elements and support for common functions

********************************************************************************************}

{                                                                                 }
{                                                                                 }
{ All routines are documented as to whether the Extensions Strip implementation  }
{ of them they may move memory.  You can trust that a routine that says it         }
{ will not move memory in this version, will not move memory in future versions. }
{ Note though, that some Universal Control Strip traps may move memory under     }
{ Control/Desktop Strip but not in Extensions Strip (such as                     }
{ _SBIsControlStripVisible and _SBShowHideControlStrip.)                         }
{                                                                                 }
{                                                                                 }

{ ========================================================= }
{ ========== Universal Control Strip traps ================ }
{ ========================================================= }

            { Will not move memory. }
{FUNCTION SBIsControlStripVisible: BOOLEAN;}

            { Will not move memory. }
{PROCEDURE SBShowHideControlStrip(showIt: BOOLEAN);}

            { Will not move memory. }
{FUNCTION SBSafeToAccessStartupDisk: BOOLEAN;}

            { May move memory! }
{FUNCTION SBOpenModuleResourceFile(fileCreator: OSType): INTEGER;}

            { May move memory! }
{FUNCTION SBLoadPreferences(prefsResourceName: ConstStr255Param; VAR preferences: Handle): OSErr;}

            { May move memory! }
{FUNCTION SBSavePreferences(prefsResourceName: ConstStr255Param; preferences: Handle): OSErr;}

            { Will not move memory. }
{PROCEDURE SBGetDetachedIndString(theString: StringPtr; stringList: Handle; whichString: INTEGER);}

            { May move memory! }
{FUNCTION SBGetDetachIconSuite(VAR theIconSuite: Handle; theResID: INTEGER; selector: LONGINT): OSErr;}

            { May move memory! }
{FUNCTION SBTrackPopupMenu(VAR moduleRect: Rect; theMenu: MenuHandle): OSErr;}

            { May move memory! }
{FUNCTION SBTrackSlider(VAR moduleRect: Rect; ticksOnSlider: INTEGER; initialValue: INTEGER): OSErr;}

            { May move memory! }
{FUNCTION SBShowHelpString(VAR moduleRect: Rect; helpString: StringPtr): OSErr;}

            { Will not move memory. }
{FUNCTION SBGetBarGraphWidth(barCount: INTEGER): INTEGER;}

            { May move memory! }
{PROCEDURE SBDrawBarGraph(level: INTEGER; barCount: INTEGER; direction: INTEGER; barGraphTopLeft: Point);}

            { May move memory! }
{PROCEDURE SBModalDialogInContext(filterProc: ModalFilterUPP; VAR itemHit: INTEGER);}

{ ======================================================= }
{ ========== Extensions Strip ONLY traps ================ }
{ ======================================================= }

{ Strip Window Utilities }

    { returns: true = vertical; false = horizontal }
    {}        { Will not move memory. }
FUNCTION SBIsControlStripVertical(stripPort: WindowRef): BOOLEAN;
    {$IFC NOT GENERATINGCFM}
    INLINE $70FF, $AAF2;
    {$ENDC}

    { returns pixel depth of the monitor this Strip window is in (always a power of 2) }
    {}        { Will not move memory. }
FUNCTION SBGetControlStripDepth(stripPort: WindowRef): INTEGER;
    {$IFC NOT GENERATINGCFM}
    INLINE $70FE, $AAF2;
    {$ENDC}

    { returns the current normal back color of this Strip window }
    {}        { Will not move memory. }
PROCEDURE SBGetStripBackColor(VAR color: RGBColor; stripPort: WindowRef);
    {$IFC NOT GENERATINGCFM}
    INLINE $70FD, $AAF2;
    {$ENDC}

    { returns the current back color of this Strip window when a module is selected }
    {}        { Will not move memory. }
PROCEDURE SBGetStripSelectedColor(VAR color: RGBColor; stripPort: WindowRef);
    {$IFC NOT GENERATINGCFM}
    INLINE $70FC, $AAF2;
    {$ENDC}

{ Module Utilities }

    { returns a reference number that all of the Module Utilities need                }
        { NB: since SBGetMyReferenceNum can ONLY be called from sdevInitModule,        }
        {   you should save its value into your globals if you are going to use        }
        {   one of the Module Utilities later, such as inside a tracking handler.    }
    { Also, the reference number will always be non-zero. }
    {}        { Will not move memory. }
FUNCTION SBGetMyReferenceNum: ModuleReference;
    {$IFC NOT GENERATINGCFM}
    INLINE $70FB, $AAF2;
    {$ENDC}

    { total window space taken up by a module.  Useful for drag-n-drop calculations }
    { note that this rect will always be larger than the module's statusRect. }
    {}        { Will not move memory. }
PROCEDURE SBGetTotalModuleBounds(VAR bounds: Rect; stripPort: WindowRef; moduleRefNum: ModuleReference);
    {$IFC NOT GENERATINGCFM}
    INLINE $70FA, $AAF2;
    {$ENDC}

    { returns the statusRect of the module.  Very useful for drag-n-drop routines }
    { because you no longer have to constantly set a global rectangle variable to }
    { hold the current location of the module in the Strip window. }
    {}        { Will not move memory. }
PROCEDURE SBGetModuleBounds(VAR bounds: Rect; moduleRefNum: ModuleReference);
    {$IFC NOT GENERATINGCFM}
    INLINE $70F9, $AAF2;
    {$ENDC}

{ Miscellaneous Utilities }

    { runs this (locked!) piece of code once within Extensions Strip's context.        }
    { PPC modules must pass a valid routine descriptor to this function.  Since        }
    { the descriptor will not be disposed of after the code has executed, I would    }
    { recommend creating the descriptor (NewSBQueueProcProc) when sdevInitModule    }
    { is called and disposing it upon sdevCloseModule.                                }
    { A non-zero result code means that the UPP could not be queued (memory error).    }
    {}        { May move memory! }
FUNCTION SBQueueCode(theProc: SBQueueUPP; refCon: LONGINT): OSErr;
    {$IFC NOT GENERATINGCFM}
    INLINE $70F8, $AAF2;
    {$ENDC}

    { sends the specified Apple Event within Extensions Strip's context to insure        }
    { safe sending rather than trusting that the front application is AE aware.            }
    { _SBSimpleAESend acts just like _AESend in that the AppleEvent you give to it        }
    { must still be disposed of afterward by your code to free up memory (even            }
    { though the event hasn't actually been sent yet.)                                    }
    {}
    { _SBSimpleAESend is meant to be an easy way to send simple events.  If you            }
    { need to check the reply AppleEvent or the _AESend error, ect., you should queue    }
    { your code (with _SBQueueCode or by having your module return 'sdevQueueModule')    }
    { and send the Apple Event yourself.  The result returned by _SBSimpleAESend        }
    { is only non-zero if an error occured while queueing the event for later sending.    }
    {}
    { Also, if an error does occur when Extensions Strip sends your AppleEvent, the        }
    { user will be notified with a dialog that _AESend failed.                            }
    {}
    { Here are the parameters I give to _AESend.  They are basic enough for most        }
    { kinds of Apple Events that modules send, hence the name _SBSimpleAESend.            }
    { err := AESend(theAppleEvent, reply,                 your specified AppleEvent        }
    {                                                    { and a dummy reply descriptor    }
    {            kAENoReply + kAEAlwaysInteract + kAECanSwitchLayer,     send mode        }
    {            kAENormalPriority,                                     send priority    }
    {            kAEDefaultTimeout,                                     time out            }
    {            nil,                                                 idleProc
    {            nil);                                                 filterProc
    {}        { May move memory! }
FUNCTION SBSimpleAESend({CONST}VAR theAppleEvent: AppleEvent): OSErr;
    {$IFC NOT GENERATINGCFM}
    INLINE $70F7, $AAF2;
    {$ENDC}


    { returns a pointer to the current event being processed.  Modififations to        }
    { the data in this pointer WILL take effect as the event gets passed along        }
    { to the other processes and jGNE filters further on in the chain.  Although    }
    { a module can use this function at any time, it is really meant to be called    }
    { within the sdevInterceptedEvent selector because this is where a module can    }
    { deny other modules the proper processing of the event (such as in the case    }
    { of a keyDown.)  Another good use for SBGetCurrentEvent() is to find the exact    }
    { point where a mouseDown occured if you have a queue of clickable objects.        }
    {}        { Will not move memory. }
TYPE
    EventRecordPtr = ^EventRecord;
FUNCTION SBGetCurrentEvent: EventRecordPtr;
    {$IFC NOT GENERATINGCFM}
    INLINE $70F6, $AAF2;
    {$ENDC}


{$ALIGN RESET}
{$POP}

{$SETC UsingIncludes := ExtensionsStripIncludes}

{$ENDC} {__EXTENSIONSSTRIP__}

{$IFC NOT UsingIncludes}
 END.
{$ENDC}